/*
// Licensed to Julian Hyde under one or more contributor license
// agreements. See the NOTICE file distributed with this work for
// additional information regarding copyright ownership.
//
// Julian Hyde licenses this file to you under the Apache License,
// Version 2.0 (the "License"); you may not use this file except in
// compliance with the License. You may obtain a copy of the License at:
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
 */
package org.olap4j;

import org.olap4j.metadata.Member;

import java.sql.*;
import java.util.Set;

/**
 * Information about an OLAP database.
 * 
 * <p>
 * Methods are provided to query the metadata catalog of the database. There is a method for each metadata class, and
 * each method takes zero or more parameters to qualify the instances should be returned, and returns a JDBC
 * {@link java.sql.ResultSet}.
 * 
 * <p>
 * For example, {@link #getCubes} returns the description of a cube.
 * 
 * @author jhyde
 * @since Oct 12, 2006
 */
public interface OlapDatabaseMetaData extends DatabaseMetaData, OlapWrapper {

	// override return type
	/**
	 * {@inheritDoc}
	 */
	OlapConnection getConnection() throws SQLException;

	/**
	 * Returns the granularity of changes to cell sets that the database is capable of providing.
	 * 
	 * <p>
	 * It's optional whether an olap4j provider supports cellset listeners, and also optional which granularities it
	 * supports. If the provider does not support the cell set listener API, returns an empty set. Never returns null.
	 * 
	 * @return set of the granularities that are supported when listening for changes to a cell set, never null
	 */
	Set<CellSetListener.Granularity> getSupportedCellSetListenerGranularities() throws OlapException;

	/**
	 * Retrieves a result set describing the Actions in this database.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_ACTIONS schema rowset.
	 * 
	 * <p>
	 * Each action description has the following columns:
	 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of the database.</li>
	 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of the schema to which this action belongs.</li>
	 * <li><b>CUBE_NAME</b> String => The name of the cube to which this action belongs.</li>
	 * <li><b>ACTION_NAME</b> String => The name of the action.</li>
	 * <li><b>COORDINATE</b> String => null</li>
	 * <li><b>COORDINATE_TYPE</b> int => null</li> </ol>
	 * 
	 * @param catalog
	 *            a catalog name; must match the catalog name as it is stored in the database; "" retrieves those
	 *            without a catalog; <code>null</code> means that the catalog name should not be used to narrow the
	 *            search
	 * 
	 * @param schemaPattern
	 *            a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those
	 *            without a schema; <code>null</code> means that the schema name should not be used to narrow the search
	 * 
	 * @param cubeNamePattern
	 *            a cube name pattern; must match the cube name as it is stored in the database; "" retrieves those
	 *            without a cube (such as shared dimensions); <code>null</code> means that the cube name should not be
	 *            used to narrow the search
	 * 
	 * @param actionNamePattern
	 *            an action name pattern; must match the action name as it is stored in the database; <code>null</code>
	 *            means that the action name should not be used to narrow the search
	 * 
	 * @return a <code>ResultSet</code> object in which each row is an action description
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 */
	ResultSet getActions(String catalog, String schemaPattern, String cubeNamePattern, String actionNamePattern)
			throws OlapException;

	/**
	 * Retrieves a row set describing the databases that are available on the server.
	 * 
	 * <p>
	 * Specification as for XML/A DISCOVER_DATASOURCES schema rowset.
	 * 
	 * <ol>
	 * <li><b>DATA_SOURCE_NAME</b> String => The name of the data source, such as FoodMart 2000.</li>
	 * <li><b>DATA_SOURCE_DESCRIPTION</b> String => A description of the data source, as entered by the publisher. (may
	 * be <code>null</code>)</li>
	 * <li><b>URL</b> String => The unique path that shows where to invoke the XML for Analysis methods for that data
	 * source. (may be <code>null</code>)</li>
	 * <li><b>DATA_SOURCE_INFO</b> String => A string containing any additional information required to connect to the
	 * data source. This can include the Initial Catalog property or other information for the provider.<br/>
	 * Example: "Provider=MSOLAP;Data Source=Local;" (may be <code>null</code>)</li>
	 * <li><b>PROVIDER_NAME</b> String => The name of the provider behind the data source. <br/>
	 * Example: "MSDASQL" (may be <code>null</code>)</li>
	 * <li><b>PROVIDER_TYPE</b> EnumerationArray => The types of data supported by the provider. May include one or more
	 * of the following types. Example follows this table.<br/>
	 * TDP: tabular data provider.<br/>
	 * MDP: multidimensional data provider.<br/>
	 * DMP: data mining provider. A DMP provider implements the OLE DB for Data Mining specification.</li>
	 * <li><b>AUTHENTICATION_MODE</b> EnumString => Specification of what type of security mode the data source uses.
	 * Values can be one of the following:<br/>
	 * Unauthenticated: no user ID or password needs to be sent.<br/>
	 * Authenticated: User ID and Password must be included in the information required for the connection.<br/>
	 * Integrated: the data source uses the underlying security to determine authorization, such as Integrated Security
	 * provided by Microsoft Internet Information Services (IIS).</li>
	 * </ol>
	 * 
	 * @return a <code>ResultSet</code> object in which each row is an OLAP database description
	 * @throws OlapException
	 *             if a database access error occurs
	 */
	ResultSet getDatabases() throws OlapException;

	/**
	 * Retrieves a list of information on supported literals, including data types and values.
	 * 
	 * <p>
	 * Specification as for XML/A DISCOVER_LITERALS schema rowset.
	 * 
	 * <ol>
	 * <li><b>LITERAL_NAME</b> String => The name of the literal described in the row.<br/>
	 * Example: DBLITERAL_LIKE_PERCENT</li>
	 * <li><b>LITERAL_VALUE</b> String (may be <code>null</code>) => Contains the actual literal value.<br/>
	 * Example, if LiteralName is DBLITERAL_LIKE_PERCENT and the percent character (%) is used to match zero or more
	 * characters in a LIKE clause, this column's value would be "%".</li>
	 * <li><b>LITERAL_INVALID_CHARS</b> String (may be <code>null</code>) => The characters, in the literal, that are
	 * not valid.<br/>
	 * For example, if table names can contain anything other than a numeric character, this string would be
	 * "0123456789".</li>
	 * <li><b>LITERAL_INVALID_STARTING_CHARS</b> String (may be <code>null</code>) => The characters that are not valid
	 * as the first character of the literal. If the literal can start with any valid character, this is null.</li>
	 * <li><b>LITERAL_MAX_LENGTH</b> int (may be <code>null</code>) => The maximum number of characters in the literal.
	 * If there is no maximum or the maximum is unknown, the value is -1.</li>
	 * </ol>
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a literal description
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 */
	ResultSet getLiterals() throws OlapException;

	/**
	 * Retrieves a list of the standard and provider-specific properties supported by an olap4j provider. Properties
	 * that are not supported by a provider are not listed in the return result set.
	 * 
	 * <p>
	 * Specification as for XML/A DISCOVER_PROPERTIES schema rowset.
	 * 
	 * <p>
	 * Not to be confused with {@link #getProperties}.
	 * 
	 * <ol>
	 * <li><b>PROPERTY_NAME</b> String => The name of the property.</li>
	 * <li><b>PROPERTY_DESCRIPTION</b> String => A localizable text description of the property.</li>
	 * <li><b>PROPERTY_TYPE</b> String => The XML data type of the property.</li>
	 * <li><b>PROPERTY_ACCESS_TYPE</b> EnumString => Access for the property. The value can be Read, Write, or
	 * ReadWrite.</li>
	 * <li><b>IS_REQUIRED</b> Boolean => True if a property is required, false if it is not required.</li>
	 * <li><b>PROPERTY_VALUE</b> String => The current value of the property.</li>
	 * </ol>
	 * 
	 * @param dataSourceName
	 *            Name of data source
	 * 
	 * @param propertyNamePattern
	 *            an property name pattern; must match the property name as it is stored in the database;
	 *            <code>null</code> means that the property name should not be used to narrow the search
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a the description of a database property
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 */
	ResultSet getDatabaseProperties(String dataSourceName, String propertyNamePattern) throws OlapException;

	/**
	 * Retrieves a result set describing member and cell Properties.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_PROPERTIES schema rowset.
	 * 
	 * <p>
	 * Not to be confused with {@link #getDatabaseProperties(String,String)}.
	 * 
	 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of the database.</li>
	 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of the schema to which this property
	 * belongs.</li>
	 * <li><b>CUBE_NAME</b> String => The name of the cube.</li>
	 * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the dimension.</li>
	 * <li><b>HIERARCHY_UNIQUE_NAME</b> String => The unique name of the hierarchy.</li>
	 * <li><b>LEVEL_UNIQUE_NAME</b> String => The unique name of the level to which this property belongs.</li>
	 * <li><b>MEMBER_UNIQUE_NAME</b> String (may be <code>null</code>) => The unique name of the member to which the
	 * property belongs.</li>
	 * <li><b>PROPERTY_NAME</b> String => Name of the property.</li>
	 * <li><b>PROPERTY_CAPTION</b> String => A label or caption associated with the property, used primarily for display
	 * purposes.</li>
	 * <li><b>PROPERTY_TYPE</b> Short => A bitmap that specifies the type of the property</li>
	 * <li><b>DATA_TYPE</b> UnsignedShort => Data type of the property.</li>
	 * <li><b>PROPERTY_CONTENT_TYPE</b> Short (may be <code>null</code>) => The type of the property.</li>
	 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A human-readable description of the measure.</li>
	 * </ol>
	 * 
	 * @param catalog
	 *            a catalog name; must match the catalog name as it is stored in the database; "" retrieves those
	 *            without a catalog; <code>null</code> means that the catalog name should not be used to narrow the
	 *            search
	 * 
	 * @param schemaPattern
	 *            a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those
	 *            without a schema; <code>null</code> means that the schema name should not be used to narrow the search
	 * 
	 * @param cubeNamePattern
	 *            a cube name pattern; must match the cube name as it is stored in the database; "" retrieves those
	 *            without a cube; <code>null</code> means that the cube name should not be used to narrow the search
	 * 
	 * @param dimensionUniqueName
	 *            unique name of a dimension (not a pattern); must match the dimension name as it is stored in the
	 *            database; <code>null</code> means that the dimension name should not be used to narrow the search
	 * 
	 * @param hierarchyUniqueName
	 *            unique name of a hierarchy (not a pattern); must match the hierarchy name as it is stored in the
	 *            database; <code>null</code> means that the hierarchy name should not be used to narrow the search
	 * 
	 * @param levelUniqueName
	 *            unique name of a level (not a pattern); must match the level name as it is stored in the database;
	 *            <code>null</code> means that the level name should not be used to narrow the search
	 * 
	 * @param memberUniqueName
	 *            unique name of member (not a pattern); <code>null</code> means that the member unique name should not
	 *            be used to narrow the search
	 * 
	 * @param propertyNamePattern
	 *            a property name pattern; must match the property name as it is stored in the database;
	 *            <code>null</code> means that the property name should not be used to narrow the search
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a description of a member or cell property
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 * @see org.olap4j.metadata.Property
	 */
	ResultSet getProperties(String catalog, String schemaPattern, String cubeNamePattern, String dimensionUniqueName,
			String hierarchyUniqueName, String levelUniqueName, String memberUniqueName, String propertyNamePattern)
			throws OlapException;

	/**
	 * Retrieves a comma-separated list of all of this database's MDX keywords.
	 * 
	 * @return the list of this database's MDX keywords
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 */
	String getMdxKeywords() throws OlapException;

	/**
	 * Retrieves a result set describing the Cubes in this database.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_CUBES schema rowset.
	 * 
	 * <p>
	 * Each cube description has the following columns:
	 * <ol>
	 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of the catalog to which this cube belongs.</li>
	 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of the schema to which this cube belongs.</li>
	 * <li><b>CUBE_NAME</b> String => Name of the cube.</li>
	 * <li><b>CUBE_TYPE</b> String => Cube type.</li>
	 * <li><b>CUBE_GUID</b> UUID (may be <code>null</code>) => Cube type.</li>
	 * <li><b>CREATED_ON</b> Timestamp (may be <code>null</code>) => Date and time of cube creation.</li>
	 * <li><b>LAST_SCHEMA_UPDATE</b> Timestamp (may be <code>null</code>) => Date and time of last schema update.</li>
	 * <li><b>SCHEMA_UPDATED_BY</b> String (may be <code>null</code>) => User ID of the person who last updated the
	 * schema.</li>
	 * <li><b>LAST_DATA_UPDATE</b> Timestamp (may be <code>null</code>) => Date and time of last data update.</li>
	 * <li><b>DATA_UPDATED_BY</b> String (may be <code>null</code>) => User ID of the person who last updated the data.</li>
	 * <li><b>IS_DRILLTHROUGH_ENABLED</b> boolean => Describes whether DRILLTHROUGH can be performed on the members of a
	 * cube</li>
	 * <li><b>IS_WRITE_ENABLED</b> boolean => Describes whether a cube is write-enabled</li>
	 * <li><b>IS_LINKABLE</b> boolean => Describes whether a cube can be used in a linked cube</li>
	 * <li><b>IS_SQL_ENABLED</b> boolean => Describes whether or not SQL can be used on the cube</li>
	 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A user-friendly description of the cube.</li>
	 * <li><b>CUBE_CAPTION</b> String (may be <code>null</code>) => The caption of the cube.</li>
	 * <li><b>BASE_CUBE_NAME</b> String (may be <code>null</code>) => The name of the source cube if this cube is a
	 * perspective cube.</li>
	 * </ol>
	 * 
	 * @param catalog
	 *            a catalog name; must match the catalog name as it is stored in the database; "" retrieves those
	 *            without a catalog; <code>null</code> means that the catalog name should not be used to narrow the
	 *            search
	 * 
	 * @param schemaPattern
	 *            a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those
	 *            without a schema; <code>null</code> means that the schema name should not be used to narrow the search
	 * 
	 * @param cubeNamePattern
	 *            a cube name pattern; must match the cube name as it is stored in the database; <code>null</code> means
	 *            that the cube name should not be used to narrow the search
	 * 
	 * @return <code>ResultSet</code> in which each row is a cube description
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 * @see org.olap4j.metadata.Cube
	 */
	public ResultSet getCubes(String catalog, String schemaPattern, String cubeNamePattern) throws OlapException;

	/**
	 * Retrieves a result set describing the shared and private Dimensions in this database.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_DIMENSIONS schema rowset.
	 * 
	 * <p>
	 * Each dimension description has the following columns:
	 * <ol>
	 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of the database.</li>
	 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => Not supported.</li>
	 * <li><b>CUBE_NAME</b> String => The name of the cube.</li>
	 * <li><b>DIMENSION_NAME</b> String => The name of the dimension.</li>
	 * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the dimension.</li>
	 * <li><b>DIMENSION_GUID</b> String (may be <code>null</code>) => Not supported.</li>
	 * <li><b>DIMENSION_CAPTION</b> String => The caption of the dimension.</li>
	 * <li><b>DIMENSION_ORDINAL</b> int => The position of the dimension within the cube.</li>
	 * <li><b>DIMENSION_TYPE</b> Short => The type of the dimension.</li>
	 * <li><b>DIMENSION_CARDINALITY</b> int => The number of members in the key attribute.</li>
	 * <li><b>DEFAULT_HIERARCHY</b> String => A hierarchy from the dimension. Preserved for backwards compatibility.</li>
	 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A user-friendly description of the dimension.</li>
	 * <li><b>IS_VIRTUAL</b> boolean (may be <code>null</code>) => Always FALSE.</li>
	 * <li><b>IS_READWRITE</b> boolean (may be <code>null</code>) => A Boolean that indicates whether the dimension is
	 * write-enabled.</li>
	 * <li><b>DIMENSION_UNIQUE_SETTINGS</b> int (may be <code>null</code>) => A bitmap that specifies which columns
	 * contain unique values if the dimension contains only members with unique names.</li>
	 * <li><b>DIMENSION_MASTER_UNIQUE_NAME</b> String (may be <code>null</code>) => Always NULL.</li>
	 * <li><b>DIMENSION_IS_VISIBLE</b> boolean (may be <code>null</code>) => Always TRUE.</li>
	 * </ol>
	 * 
	 * @param catalog
	 *            a catalog name; must match the catalog name as it is stored in the database; "" retrieves those
	 *            without a catalog; <code>null</code> means that the catalog name should not be used to narrow the
	 *            search
	 * 
	 * @param schemaPattern
	 *            a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those
	 *            without a schema; <code>null</code> means that the schema name should not be used to narrow the search
	 * 
	 * @param cubeNamePattern
	 *            a cube name pattern; must match the cube name as it is stored in the database; "" retrieves those
	 *            without a cube (such as shared dimensions); <code>null</code> means that the cube name should not be
	 *            used to narrow the search
	 * 
	 * @param dimensionNamePattern
	 *            a dimension name pattern; must match the dimension name as it is stored in the database;
	 *            <code>null</code> means that the dimension name should not be used to narrow the search
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a dimension description
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 * @see org.olap4j.metadata.Dimension
	 */
	ResultSet getDimensions(String catalog, String schemaPattern, String cubeNamePattern, String dimensionNamePattern)
			throws OlapException;

	/**
	 * Retrieves a result set describing the Functions available to client applications connected to the database.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_FUNCTIONS schema rowset.
	 * 
	 * <p>
	 * Each function description has the following columns:
	 * <li><b>FUNCTION_NAME</b> String => The name of the function.</li>
	 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A description of the function.</li>
	 * <li><b>PARAMETER_LIST</b> String (may be <code>null</code>) => A comma delimited list of parameters.</li>
	 * <li><b>RETURN_TYPE</b> int => The VARTYPE of the return data type of the function.</li>
	 * <li><b>ORIGIN</b> int => The origin of the function: 1 for MDX functions. 2 for user-defined functions.</li>
	 * <li><b>INTERFACE_NAME</b> String => The name of the interface for user-defined functions</li>
	 * <li><b>LIBRARY_NAME</b> String (may be <code>null</code>) => The name of the type library for user-defined
	 * functions. NULL for MDX functions.</li>
	 * <li><b>CAPTION</b> String (may be <code>null</code>) => The display caption for the function.</li> </ol>
	 * 
	 * @param functionNamePattern
	 *            a function name pattern; must match the function name as it is stored in the database;
	 *            <code>null</code> means that the function name should not be used to narrow the search
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a function description
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 */
	// NOTE: '#getFunctions(String, String, String)' above generates a javadoc
	// error on JDK 1.5, because it is new in JDBC 4.0/JDK 1.6. But please leave
	// it in. Most olap4j users run on JDK 1.6 or later, and the javadoc is
	// intended for them.
	ResultSet getOlapFunctions(String functionNamePattern) throws OlapException;

	/**
	 * Retrieves a result set describing the Hierarchies in this database.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_HIERARCHIES schema rowset.
	 * 
	 * <p>
	 * Each hierarchy description has the following columns:
	 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of the catalog to which this hierarchy
	 * belongs.</li>
	 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => Not supported</li>
	 * <li><b>CUBE_NAME</b> String => The name of the cube to which this hierarchy belongs.</li>
	 * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the dimension to which this hierarchy belongs.</li>
	 * <li><b>HIERARCHY_NAME</b> String => The name of the hierarchy. Blank if there is only a single hierarchy in the
	 * dimension.</li>
	 * <li><b>HIERARCHY_UNIQUE_NAME</b> String => The unique name of the hierarchy.</li>
	 * <li><b>HIERARCHY_GUID</b> String (may be <code>null</code>) => Hierarchy GUID.</li>
	 * <li><b>HIERARCHY_CAPTION</b> String => A label or a caption associated with the hierarchy.</li>
	 * <li><b>DIMENSION_TYPE</b> Short => The type of the dimension.</li>
	 * <li><b>HIERARCHY_CARDINALITY</b> int => The number of members in the hierarchy.</li>
	 * <li><b>DEFAULT_MEMBER</b> String (may be <code>null</code>) => The default member for this hierarchy.</li>
	 * <li><b>ALL_MEMBER</b> String (may be <code>null</code>) => The member at the highest level of rollup in the
	 * hierarchy.</li>
	 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A human-readable description of the hierarchy. NULL
	 * if no description exists.</li>
	 * <li><b>STRUCTURE</b> Short => The structure of the hierarchy.</li>
	 * <li><b>IS_VIRTUAL</b> boolean => Always returns False.</li>
	 * <li><b>IS_READWRITE</b> boolean => A Boolean that indicates whether the Write Back to dimension column is
	 * enabled.</li>
	 * <li><b>DIMENSION_UNIQUE_SETTINGS</b> int => Always returns MDDIMENSIONS_MEMBER_KEY_UNIQUE (1).</li>
	 * <li><b>DIMENSION_IS_VISIBLE</b> boolean => Always returns true.</li>
	 * <li><b>HIERARCHY_ORDINAL</b> int => The ordinal number of the hierarchy across all hierarchies of the cube.</li>
	 * <li><b>DIMENSION_IS_SHARED</b> boolean => Always returns true.</li>
	 * <li><b>PARENT_CHILD</b> boolean (may be <code>null</code>) => Is hierarchy a parent.</li> </ol>
	 * 
	 * @param catalog
	 *            a catalog name; must match the catalog name as it is stored in the database; "" retrieves those
	 *            without a catalog; <code>null</code> means that the catalog name should not be used to narrow the
	 *            search
	 * 
	 * @param schemaPattern
	 *            a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those
	 *            without a schema; <code>null</code> means that the schema name should not be used to narrow the search
	 * 
	 * @param cubeNamePattern
	 *            a cube name pattern; must match the cube name as it is stored in the database; "" retrieves those
	 *            without a cube; <code>null</code> means that the cube name should not be used to narrow the search
	 * 
	 * @param dimensionUniqueName
	 *            unique name of a dimension (not a pattern); must match the dimension name as it is stored in the
	 *            database; <code>null</code> means that the dimension name should not be used to narrow the search
	 * 
	 * @param hierarchyNamePattern
	 *            a hierarchy name pattern; must match the hierarchy name as it is stored in the database;
	 *            <code>null</code> means that the hierarchy name should not be used to narrow the search
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a hierarchy description
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 * @see org.olap4j.metadata.Hierarchy
	 */
	ResultSet getHierarchies(String catalog, String schemaPattern, String cubeNamePattern, String dimensionUniqueName,
			String hierarchyNamePattern) throws OlapException;

	/**
	 * Retrieves a result set describing the Levels in this database.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_LEVELS schema rowset.
	 * 
	 * <p>
	 * Each level description has the following columns:
	 * <ol>
	 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of the catalog to which this level belongs.
	 * </li>
	 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of the schema to which this level belongs.</li>
	 * <li><b>CUBE_NAME</b> String => The name of the cube to which this level belongs.</li>
	 * <li><b>DIMENSION_UNIQUE_NAME</b> String => The unique name of the dimension to which this level belongs.</li>
	 * <li><b>HIERARCHY_UNIQUE_NAME</b> String => The unique name of the hierarchy.</li>
	 * <li><b>LEVEL_NAME</b> String => The name of the level.</li>
	 * <li><b>LEVEL_UNIQUE_NAME</b> String => The properly escaped unique name of the level.</li>
	 * <li><b>LEVEL_GUID</b> String (may be <code>null</code>) => Level GUID.</li>
	 * <li><b>LEVEL_CAPTION</b> String => A label or caption associated with the hierarchy.</li>
	 * <li><b>LEVEL_NUMBER</b> int => The distance of the level from the root of the hierarchy. Root level is zero (0).</li>
	 * <li><b>LEVEL_CARDINALITY</b> int => The number of members in the level. This value can be an approximation of the
	 * real cardinality.</li>
	 * <li><b>LEVEL_TYPE</b> int => Type of the level</li>
	 * <li><b>CUSTOM_ROLLUP_SETTINGS</b> int => A bitmap that specifies the custom rollup options.</li>
	 * <li><b>LEVEL_UNIQUE_SETTINGS</b> int => A bitmap that specifies which columns contain unique values, if the level
	 * only has members with unique names or keys.</li>
	 * <li><b>LEVEL_IS_VISIBLE</b> boolean => A Boolean that indicates whether the level is visible.</li>
	 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A human-readable description of the level. NULL if no
	 * description exists.</li>
	 * </ol>
	 * 
	 * @param catalog
	 *            a catalog name; must match the catalog name as it is stored in the database; "" retrieves those
	 *            without a catalog; <code>null</code> means that the catalog name should not be used to narrow the
	 *            search
	 * 
	 * @param schemaPattern
	 *            a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those
	 *            without a schema; <code>null</code> means that the schema name should not be used to narrow the search
	 * 
	 * @param cubeNamePattern
	 *            a cube name pattern; must match the cube name as it is stored in the database; "" retrieves those
	 *            without a cube; <code>null</code> means that the cube name should not be used to narrow the search
	 * 
	 * @param dimensionUniqueName
	 *            unique name of a dimension (not a pattern); must match the dimension name as it is stored in the
	 *            database; <code>null</code> means that the dimension name should not be used to narrow the search
	 * 
	 * @param hierarchyUniqueName
	 *            unique name of a hierarchy (not a pattern); must match the hierarchy name as it is stored in the
	 *            database; <code>null</code> means that the hierarchy name should not be used to narrow the search
	 * 
	 * @param levelNamePattern
	 *            a level name pattern; must match the level name as it is stored in the database; <code>null</code>
	 *            means that the level name should not be used to narrow the search
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a level description
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 * @see org.olap4j.metadata.Level
	 */
	ResultSet getLevels(String catalog, String schemaPattern, String cubeNamePattern, String dimensionUniqueName,
			String hierarchyUniqueName, String levelNamePattern) throws OlapException;

	/**
	 * Retrieves a result set describing the Measures in this database.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_MEASURES schema rowset.
	 * 
	 * <p>
	 * Each measure description has the following columns:
	 * <ol>
	 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of the catalog to which this measure
	 * belongs.</li>
	 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of the schema to which this measure belongs.
	 * </li>
	 * <li><b>CUBE_NAME</b> String => The name of the cube to which this measure belongs.</li>
	 * <li><b>MEASURE_NAME</b> String => The name of the measure.</li>
	 * <li><b>MEASURE_UNIQUE_NAME</b> String => The Unique name of the measure.</li>
	 * <li><b>MEASURE_CAPTION</b> String => A label or caption associated with the measure.</li>
	 * <li><b>MEASURE_GUID</b> String (may be <code>null</code>) => Measure GUID.</li>
	 * <li><b>MEASURE_AGGREGATOR</b> int => How a measure was derived.</li>
	 * <li><b>DATA_TYPE</b> UnsignedShort => Data type of the measure.</li>
	 * <li><b>MEASURE_IS_VISIBLE</b> boolean => A Boolean that always returns True. If the measure is not visible, it
	 * will not be included in the schema rowset.</li>
	 * <li><b>LEVELS_LIST</b> String (may be <code>null</code>) => A string that always returns NULL. EXCEPT that SQL
	 * Server returns non-null values!!!</li>
	 * <li><b>DESCRIPTION</b> String (may be <code>null</code>) => A human-readable description of the measure.</li>
	 * </ol>
	 * 
	 * @param catalog
	 *            a catalog name; must match the catalog name as it is stored in the database; "" retrieves those
	 *            without a catalog; <code>null</code> means that the catalog name should not be used to narrow the
	 *            search
	 * 
	 * @param schemaPattern
	 *            a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those
	 *            without a schema; <code>null</code> means that the schema name should not be used to narrow the search
	 * 
	 * @param cubeNamePattern
	 *            a cube name pattern; must match the cube name as it is stored in the database; "" retrieves those
	 *            without a cube; <code>null</code> means that the cube name should not be used to narrow the search
	 * 
	 * @param measureNamePattern
	 *            a measure name pattern; must match the measure name as it is stored in the database; <code>null</code>
	 *            means that the measure name should not be used to narrow the search
	 * 
	 * @param measureUniqueName
	 *            unique name of measure (not a pattern); <code>null</code> means that the measure unique name should
	 *            not be used to narrow the search
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a measure description
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 * @see org.olap4j.metadata.Measure
	 */
	ResultSet getMeasures(String catalog, String schemaPattern, String cubeNamePattern, String measureNamePattern,
			String measureUniqueName) throws OlapException;

	/**
	 * Retrieves a result set describing the Members in this database.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_MEMBERS schema rowset. Rows are sorted by level number then by ordinal.
	 * 
	 * <p>
	 * The <code>treeOps</code> parameter allows you to retrieve members relative to a given member. It is only
	 * applicable if a <code>memberUniqueName</code> is also specified; otherwise it is ignored. The following example
	 * retrieves all descendants and ancestors of California, but not California itself:
	 * 
	 * <blockquote>
	 * 
	 * <pre>
	 * OlapDatabaseMetaData metaData;
	 * ResultSet rset = metaData.getMembers(&quot;LOCALDB&quot;, &quot;FoodMart&quot;, &quot;Sales&quot;, null, null, null, &quot;[Customers].[USA].[CA]&quot;,
	 * 		EnumSet.of(Member.TreeOp.ANCESTORS, Member.TreeOp.DESCENDANTS));
	 * </pre>
	 * 
	 * </blockquote>
	 * 
	 * <p>
	 * Each member description has the following columns:
	 * <ol>
	 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => The name of the catalog to which this member
	 * belongs.</li>
	 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => The name of the schema to which this member belongs.</li>
	 * <li><b>CUBE_NAME</b> String => Name of the cube to which this member belongs.</li>
	 * <li><b>DIMENSION_UNIQUE_NAME</b> String => Unique name of the dimension to which this member belongs.</li>
	 * <li><b>HIERARCHY_UNIQUE_NAME</b> String => Unique name of the hierarchy. If the member belongs to more than one
	 * hierarchy, there is one row for each hierarchy to which it belongs.</li>
	 * <li><b>LEVEL_UNIQUE_NAME</b> String => Unique name of the level to which the member belongs.</li>
	 * <li><b>LEVEL_NUMBER</b> int => The distance of the member from the root of the hierarchy.</li>
	 * <li><b>MEMBER_ORDINAL</b> int => Ordinal number of the member. Sort rank of the member when members of this
	 * dimension are sorted in their natural sort order. If providers do not have the concept of natural ordering, this
	 * should be the rank when sorted by MEMBER_NAME.</li>
	 * <li><b>MEMBER_NAME</b> String => Name of the member.</li>
	 * <li><b>MEMBER_UNIQUE_NAME</b> String => Unique name of the member.</li>
	 * <li><b>MEMBER_TYPE</b> int => Type of the member.</li>
	 * <li><b>MEMBER_GUID</b> String (may be <code>null</code>) => Memeber GUID.</li>
	 * <li><b>MEMBER_CAPTION</b> String => A label or caption associated with the member.</li>
	 * <li><b>CHILDREN_CARDINALITY</b> int => Number of children that the member has.</li>
	 * <li><b>PARENT_LEVEL</b> int => The distance of the member's parent from the root level of the hierarchy.</li>
	 * <li><b>PARENT_UNIQUE_NAME</b> String (may be <code>null</code>) => Unique name of the member's parent.</li>
	 * <li><b>PARENT_COUNT</b> int => Number of parents that this member has.</li>
	 * <li><b>TREE_OP</b> Enumeration (may be <code>null</code>) => Tree Operation</li>
	 * <li><b>DEPTH</b> int (may be <code>null</code>) => depth</li>
	 * </ol>
	 * 
	 * @param catalog
	 *            a catalog name; must match the catalog name as it is stored in the database; "" retrieves those
	 *            without a catalog; <code>null</code> means that the catalog name should not be used to narrow the
	 *            search
	 * 
	 * @param schemaPattern
	 *            a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those
	 *            without a schema; <code>null</code> means that the schema name should not be used to narrow the search
	 * 
	 * @param cubeNamePattern
	 *            a cube name pattern; must match the cube name as it is stored in the database; "" retrieves those
	 *            without a cube; <code>null</code> means that the cube name should not be used to narrow the search
	 * 
	 * @param dimensionUniqueName
	 *            unique name of dimension (not a pattern); must match the dimension name as it is stored in the
	 *            database; <code>null</code> means that the dimension name should not be used to narrow the search
	 * 
	 * @param hierarchyUniqueName
	 *            unique name of hierarchy (not a pattern); must match the hierarchy name as it is stored in the
	 *            database; <code>null</code> means that the hierarchy name should not be used to narrow the search
	 * 
	 * @param levelUniqueName
	 *            unique name of level (not a pattern); must match the level name as it is stored in the database;
	 *            <code>null</code> means that the level name should not be used to narrow the search
	 * 
	 * @param memberUniqueName
	 *            unique name of member (not a pattern); <code>null</code> means that the measure unique name should not
	 *            be used to narrow the search
	 * 
	 * @param treeOps
	 *            set of tree operations to retrieve members relative to the member whose unique name was specified; or
	 *            null to return just the member itself. Ignored if <code>memberUniqueName</code> is not specified.
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a member description
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 * @see org.olap4j.metadata.Member
	 */
	ResultSet getMembers(String catalog, String schemaPattern, String cubeNamePattern, String dimensionUniqueName,
			String hierarchyUniqueName, String levelUniqueName, String memberUniqueName, Set<Member.TreeOp> treeOps)
			throws OlapException;

	/**
	 * Retrieves a result set describing the named Sets in this database.
	 * 
	 * <p>
	 * Specification as for XML/A MDSCHEMA_SETS schema rowset.
	 * 
	 * <p>
	 * Each set description has the following columns:
	 * <ol>
	 * <li><b>CATALOG_NAME</b> String (may be <code>null</code>) => null</li>
	 * <li><b>SCHEMA_NAME</b> String (may be <code>null</code>) => null</li>
	 * <li><b>CUBE_NAME</b> String => null</li>
	 * <li><b>SET_NAME</b> String => null</li>
	 * <li><b>SCOPE</b> int => null</li>
	 * 
	 * @param catalog
	 *            a catalog name; must match the catalog name as it is stored in the database; "" retrieves those
	 *            without a catalog; <code>null</code> means that the catalog name should not be used to narrow the
	 *            search
	 * 
	 * @param schemaPattern
	 *            a schema name pattern; must match the schema name as it is stored in the database; "" retrieves those
	 *            without a schema; <code>null</code> means that the schema name should not be used to narrow the search
	 * 
	 * @param cubeNamePattern
	 *            a cube name pattern; must match the cube name as it is stored in the database; "" retrieves those
	 *            without a cube; <code>null</code> means that the cube name should not be used to narrow the search
	 * 
	 * @param setNamePattern
	 *            pattern for the unique name of a set; must match the set name as it is stored in the database; <code>
	 *            null</code> means that the set name should not be used to narrow the search
	 * 
	 * @return a <code>ResultSet</code> object in which each row is a description of a named set
	 * 
	 * @exception OlapException
	 *                if a database access error occurs
	 * 
	 * @see #getSearchStringEscape
	 * @see org.olap4j.metadata.NamedSet
	 */
	ResultSet getSets(String catalog, String schemaPattern, String cubeNamePattern, String setNamePattern)
			throws OlapException;
}

// End OlapDatabaseMetaData.java
